<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN">
<html>
<head>
<title>SYS_FS_DriveFormat Function</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="generator" content="Doc-O-Matic" />
    <meta http-equiv="Content-Style-Type" content="text/css" />
    <link rel="STYLESHEET" href="default.css" type="text/css" />

<script type="text/javascript" src="scripts.js"></script>
</head>
<body class="Element700" onload="onBodyLoadEx('frames.html', 'topic', '00906.html');" onmousedown="onBodyMouseDown();">

<!-- Begin Popups -->

<!-- End Popups -->

<!-- Begin Page Header -->
<div class="Element710" id="areafixed">
<div class="Element94">
<a href="01259.html" target="topic">System Service Libraries Help</a> &gt; <a href="00735.html" target="topic">File System Service Library Help</a> &gt; <a href="00736.html" target="topic">Library Interface</a> &gt; b) General Operation Functions &gt; <a href="00906.html" target="topic">SYS_FS_DriveFormat Function</a></div>
<div class="Element92">
<table width="100%" cellspacing="0" cellpadding="0">
<tr><td width="25%">
<div class="Element1">
MPLAB Harmony Core Help</div>
</td><td width="25%">
<div class="Element2">
<a href="contents.html" target="tocidx">Contents</a> | <a href="00007.html" target="topic">Home</a></div>
</td><td width="25%">
<div class="Element90">
<a href="00908.html" target="topic">Previous</a> | <a href="00736.html" target="topic">Up</a> | <a href="00909.html" target="topic">Next</a></div>
</td><td width="25%">
<div class="Element96">
<a href="mailto:docerrors@microchip.com&subject=MPLAB Harmony Documentation Feedback (Topic ID: SYS_FS_DriveFormat@char*@SYS_FS_FORMAT_PARAM*@void*@uint32_t Topic Title: SYS_FS_DriveFormat Function)&body=Thank you for your feedback! Please include a description of your feedback, and indicate whether you are reporting an an error in the documentation or an enhancement.">Documentation Feedback</a><br> <a href="http://support.microchip.com" target="_blank">Microchip Support</a></div>
</td></tr></table><div class="Element5">
SYS_FS_DriveFormat Function</div>
</div>
</div>

<!-- End Page Header -->

<!-- Begin Client Area -->
<div class="Element720" id="areascroll">
<div class="Element721">

<!-- Begin Page Content -->
<a name="PageContent"></a><div class="Element58">
<a name="4465736372697074696F6E"></a><div class="Element11">
<div class="Element10">
<p class="Element10">
This function formats a logic drive (create a FAT file system on the logical drive), as per the format specified.&nbsp;</p>
<p class="Element10">
If the logical drive that has to be formatted has been bound to any partition (1-4) by multiple partition feature, the FAT volume is created into the specified partition. The physical drive must have been partitioned prior to using this function.</p></div>
</div>
<a name="43"></a><div class="Element99">
C</div>
<div class="Element101"><div class="Element100"><pre class="Element100"><a href="01121.html" target="topic">SYS_FS_RESULT</a> <strong><span style="color: #000000">SYS_FS_DriveFormat</span></strong>(
    <strong><span style="color: #000080">const</span></strong> <strong><span style="color: #000080">char</span></strong>* <strong><span style="color: #000000">drive</span></strong>, 
    <strong><span style="color: #000080">const</span></strong> <a href="00996.html" target="topic">SYS_FS_FORMAT_PARAM</a>* <strong><span style="color: #000000">opt</span></strong>, 
    <strong><span style="color: #000080">void</span></strong>* <strong><span style="color: #000000">work</span></strong>, 
    uint32_t <strong><span style="color: #000000">len</span></strong>
);</pre></div></div>
<a name="507265636F6E646974696F6E73"></a><div class="Element14">
Preconditions</div>
<div class="Element11">
<div class="Element10">
<p class="Element10">
At least one disk must be mounted. The physical drive must have already been partitioned.</p></div>
</div>
<a name="506172616D6574657273"></a><div class="Element14">
Parameters</div>
<div class="Element11">
<div class="Element10">
<div class="Element312">
<div class="TableDiv">
<table cellspacing="0" class="Table3">
<tr>
<td class="Element300" valign="top" width="35%">
<div class="Element301">
Parameters&nbsp;</div></td><td class="Element304" valign="top" width="65%">
<div class="Element305">
Description&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
drive&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Pointer to buffer which will hold the name of drive being for which the format is to be done. If this string is NULL, then then current drive will be formatted. It is important to end the drive name with a &quot;/&quot;.&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
opt&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Specifies the structure holding format options. If a null pointer is given, fat code gives the function all options in default&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
value. The format option structure has five members described below&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
fmt - Specifies combination of FAT type flags, SYS_FS_FORMAT. These flags specify which FAT type to be created on the volume. If two or more types are specified, one out of them will be selected depends on the volume size and au_size. The default value is FM_ANY.&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
au_size&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Specifies size of the allocation unit (cluter) in unit of byte. The valid value is power of 2 between sector size and 128 * sector size inclusive for FAT/FAT32 volume and up to 16 MB. When a zero is given, the cluster size depends on the volume size.&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
n_align&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Specifies alignment of the volume data area (file allocation pool, usually erase block boundary of flash media) in unit of sector. When a zero is given, alignment is decided on the block size.&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
n_fat&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Specifies number of FAT copies on the FAT/FAT32 volume. Valid value for this member is 1 or 2. If the FAT type is exFAT, this member has no effect.&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
n_root&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Specifies number of root directory entries on the FAT volume. Valid value for this member is up to 32768 and aligned to sector size / 32. If the FAT type is FAT32 or exFAT, this member has no effect.&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
work&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Pointer to the working buffer used for the format process.&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
len&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Size of the working buffer in unit of byte. It needs to be the sector size of the corresponding physical drive at least. Plenty of working buffer reduces number of write transactions to the drive and the format process will finish quickly.&nbsp;</div></td></tr></table></div></div>
</div>
</div>
<a name="52657475726E73"></a><div class="Element14">
Returns</div>
<div class="Element11">
<div class="Element10">
<p class="Element10">
SYS_FS_RES_SUCCESS - Drive format was successful. SYS_FS_RES_FAILURE - Drive format was unsucessful. The reason for the failure can be retrieved with <a href="00911.html" target="topic">SYS_FS_Error</a>.</p></div>
</div>
<a name="52656D61726B73"></a><div class="Element14">
Remarks</div>
<div class="Element11">
<div class="Element10">
<p class="Element10">
None.</p></div>
</div>
<a name="4578616D706C65"></a><div class="Element14">
Example</div>
<div class="Element11">
<div class="Element10">
<div class="Element13"><div class="Element12"><pre class="Element12">    <a href="01121.html" target="topic">SYS_FS_RESULT</a> res;
    <a href="00996.html" target="topic">SYS_FS_FORMAT_PARAM</a> opt = { 0 };
    uint8_t CACHE_ALIGN work[512];

    <strong><span style="color: #000080">switch</span></strong>(appState)
    {
        <strong><span style="color: #000080">case</span></strong> TRY_MOUNT:
            <strong><span style="color: #000080">if</span></strong>(<a href="01117.html" target="topic">SYS_FS_Mount</a>(&quot;/dev/mmcblka1&quot;, &quot;/mnt/myDrive&quot;, FAT, 0, NULL) != SYS_FS_RES_SUCCESS)
            {
                <i><span style="color: #008000">// Failure, try mounting again</span></i>
            }
            <strong><span style="color: #000080">else</span></strong>
            {
                <i><span style="color: #008000">// Mount was successful. Format now.</span></i>
                <strong><span style="color: #000080">if</span></strong> (<a href="00911.html" target="topic">SYS_FS_Error</a>() == SYS_FS_ERROR_NO_FILESYSTEM)
                {
                    appState = FORMAT_DRIVE;
                }
                <strong><span style="color: #000080">else</span></strong>
                {
                    appState = OTHER_TASK;
                }
            }
            <strong><span style="color: #000080">break</span></strong>;

        <strong><span style="color: #000080">case</span></strong> FORMAT_DRIVE:
            opt.fmt = <a href="00993.html" target="topic">SYS_FS_FORMAT_FAT</a>;
            opt.au_size = 0;

            res = SYS_FS_DriveFormat(&quot;/mnt/myDrive&quot;, &amp;opt, (<strong><span style="color: #000080">void</span></strong> *)work, 512);
            <strong><span style="color: #000080">if</span></strong>(res == SYS_FS_RES_FAILURE)
            {
                <i><span style="color: #008000">// Format of the drive failed.</span></i>
            }
            <i><span style="color: #008000">//...</span></i>
            <strong><span style="color: #000080">break</span></strong>;
    }</pre></div></div>
</div>
</div>
</div>
<!-- End Page Content -->

<!-- Begin Page Footer -->
<div class="Element95">
<a href="01259.html" target="topic">System Service Libraries Help</a> &gt; <a href="00735.html" target="topic">File System Service Library Help</a> &gt; <a href="00736.html" target="topic">Library Interface</a> &gt; b) General Operation Functions &gt; <a href="00906.html" target="topic">SYS_FS_DriveFormat Function</a></div>
<div class="Element93">
<table width="100%" cellspacing="0" cellpadding="0">
<tr><td width="25%">
<div class="Element3">
MPLAB Harmony Core Help</div>
</td><td width="25%">
<div class="Element4">
<a href="contents.html" target="tocidx">Contents</a> | <a href="00007.html" target="topic">Home</a></div>
</td><td width="25%">
<div class="Element91">
<a href="00908.html" target="topic">Previous</a> | <a href="00736.html" target="topic">Up</a> | <a href="00909.html" target="topic">Next</a></div>
</td><td width="25%">
<div class="Element97">
<a href="mailto:docerrors@microchip.com&subject=MPLAB Harmony Documentation Feedback (Topic ID: SYS_FS_DriveFormat@char*@SYS_FS_FORMAT_PARAM*@void*@uint32_t Topic Title: SYS_FS_DriveFormat Function)&body=Thank you for your feedback! Please include a description of your feedback, and indicate whether you are reporting an an error in the documentation or an enhancement.">Documentation Feedback</a><br> <a href="http://support.microchip.com" target="_blank">Microchip Support</a></div>
</td></tr></table></div>

<!-- End Page Footer -->
</div>
</div>

<!-- End Client Area -->
</body></html>